﻿ #region Disclaimer/Info
 
 /////////////////////////////////////////////////////////////////////////////////////////////////
 //
 //   File:		ITagrepository.cs
 //   Website:		http://dexterblogengine.com/
 //   Authors:		http://dexterblogengine.com/About.ashx
 //   Rev:		1
 //   Created:		19/01/2011
 //   Last edit:		19/01/2011
 //   License:		GNU Library General Public License (LGPL)
 //   File:            ITagrepository.cs
 //   For updated news and information please visit http://dexterblogengine.com/
 //   Dexter is hosted to Codeplex at http://dexterblogengine.codeplex.com
 //   For any question contact info@dexterblogengine.com
 //
 ///////////////////////////////////////////////////////////////////////////////////////////////////
 
 #endregion

using System;
using System.Collections.Generic;
using Dexter.DataTransferObject;
using Dexter.Domain.Model;
using Dexter.Domain.Results;

namespace Dexter.Repository {
	
	/// <summary>
	/// 	Rapresents a repository of <see cref="TagItem"/>.
	/// </summary>
	public interface ITagRepository : IRepository <TagItem> {
		///<summary>
		///	Retireve a paged list of approved item, filtered by tag.
		///</summary>
		///<param name = "pageIndex">Index of the page (0 based).</param>
		///<param name = "pageSize">The number of items to retrieve.</param>
		///<param name="tagName">The tag name.</param>
		///<returns>An concrete implementation of <see cref="IPagedResult"/>. The result will never be null.</returns>
		///<exception cref="ArgumentOutOfRangeException"> If <paramref name="pageIndex"/> is lesser than 0.</exception>
		///<exception cref="ArgumentOutOfRangeException"> If <paramref name="pageSize"/> is lesser than 1.</exception>
		///<exception cref="ArgumentNullException"> If <paramref name="tagName"/> is <c>null</c> or <c>empty</c>.</exception>
		IPagedResult <Item> GetItemsByTag ( int pageIndex , int pageSize , string tagName );

		///<summary>
		///	Retireve a paged list of approved item, filtered by tag.
		///</summary>
		///<param name = "pageIndex">Index of the page (0 based).</param>
		///<param name = "pageSize">The number of items to retrieve.</param>
		///<param name="tagName">The tag name.</param>
		///<param name="includeFuturesPosts">if set to <c>true</c> the result will include the tags used in futures <see cref="Post"/>.</param>
		///<returns>An concrete implementation of <see cref="IPagedResult{T}"/>. The result will never be null.</returns>
		///<exception cref="ArgumentOutOfRangeException"> If <paramref name="pageIndex"/> is lesser than 0.</exception>
		///<exception cref="ArgumentOutOfRangeException"> If <paramref name="pageSize"/> is lesser than 1.</exception>
		///<exception cref="ArgumentNullException"> If <paramref name="tagName"/> is <c>null</c> or <c>empty</c>.</exception>
		IPagedResult <Item> GetItemsByTag ( int pageIndex , int pageSize , string tagName , bool includeFuturesPosts );

		///<summary>
		///	Retireve a paged list of approved item, filtered by tag.
		///</summary>
		///<param name = "pageIndex">Index of the page (0 based).</param>
		///<param name = "pageSize">The number of items to retrieve.</param>
		///<param name="tagName">The tag name.</param>
		///<param name="includeFuturesPosts">if set to <c>true</c> the result will include the tags used in futures <see cref="Post"/>.</param>
		///<param name = "enableTracking">if set to <c>true</c> the tracking system of the return object will be enable.</param>
		///<returns>An concrete implementation of <see cref="IPagedResult{T}"/>. The result will never be null.</returns>
		///<exception cref="ArgumentOutOfRangeException"> If <paramref name="pageIndex"/> is lesser than 0.</exception>
		///<exception cref="ArgumentOutOfRangeException"> If <paramref name="pageSize"/> is lesser than 1.</exception>
		///<exception cref="ArgumentNullException"> If <paramref name="tagName"/> is <c>null</c> or <c>empty</c>.</exception>
		IPagedResult <Item> GetItemsByTag ( int pageIndex , int pageSize , string tagName , bool includeFuturesPosts , bool enableTracking );

		///<summary>
		///	Retireve a paged list of approved posts, filtered by tag.
		///</summary>
		///<param name = "pageIndex">Index of the page (0 based).</param>
		///<param name = "pageSize">The number of items to retrieve.</param>
		///<param name="tagName">The tag name.</param>
		///<returns>An concrete implementation of <see cref="IPagedResult{T}"/>. The result will never be null.</returns>
		///<exception cref="ArgumentOutOfRangeException"> If <paramref name="pageIndex"/> is lesser than 0.</exception>
		///<exception cref="ArgumentOutOfRangeException"> If <paramref name="pageSize"/> is lesser than 1.</exception>
		///<exception cref="ArgumentNullException"> If <paramref name="tagName"/> is <c>null</c> or <c>empty</c>.</exception>
		IPagedResult<Post> GetPostsByTag ( int pageIndex, int pageSize, string tagName );

		///<summary>
		///	Retireve a paged list of approved posts, filtered by tag.
		///</summary>
		///<param name = "pageIndex">Index of the page (0 based).</param>
		///<param name = "pageSize">The number of items to retrieve.</param>
		///<param name="tagName">The tag name.</param>
		///<param name="includeFuturesPosts">if set to <c>true</c> the result will include the tags used in futures <see cref="Post"/>.</param>
		///<returns>An concrete implementation of <see cref="IPagedResult{T}"/>. The result will never be null.</returns>
		///<exception cref="ArgumentOutOfRangeException"> If <paramref name="pageIndex"/> is lesser than 0.</exception>
		///<exception cref="ArgumentOutOfRangeException"> If <paramref name="pageSize"/> is lesser than 1.</exception>
		///<exception cref="ArgumentNullException"> If <paramref name="tagName"/> is <c>null</c> or <c>empty</c>.</exception>
		IPagedResult<Post> GetPostsByTag ( int pageIndex, int pageSize, string tagName, bool includeFuturesPosts );

		///<summary>
		///	Retireve a paged list of approved posts, filtered by tag.
		///</summary>
		///<param name = "pageIndex">Index of the page (0 based).</param>
		///<param name = "pageSize">The number of items to retrieve.</param>
		///<param name="tagName">The tag name.</param>
		///<param name="includeFuturesPosts">if set to <c>true</c> the result will include the tags used in futures <see cref="Post"/>.</param>
		///<param name = "enableTracking">if set to <c>true</c> the tracking system of the return object will be enable.</param>
		///<returns>An concrete implementation of <see cref="IPagedResult{T}"/>. The result will never be null.</returns>
		///<exception cref="ArgumentOutOfRangeException"> If <paramref name="pageIndex"/> is lesser than 0.</exception>
		///<exception cref="ArgumentOutOfRangeException"> If <paramref name="pageSize"/> is lesser than 1.</exception>
		///<exception cref="ArgumentNullException"> If <paramref name="tagName"/> is <c>null</c> or <c>empty</c>.</exception>
		IPagedResult<Post> GetPostsByTag ( int pageIndex, int pageSize, string tagName, bool includeFuturesPosts, bool enableTracking );

		/// <summary>
		/// Retrieve the top used tags for all approved items.
		/// </summary>
		/// <param name="numberOfItemsToRetireve">The number of items to retireve.</param>
		///<returns>
		///	Return a list of <see cref="TagItem"/>.
		///	The return item could be null if there isn't items into the repository.
		///</returns>
		///<exception cref="ArgumentOutOfRangeException"> If <paramref name="numberOfItemsToRetireve"/> is lesser than 1.</exception>
		IList<TagDto> GetTopTags(int numberOfItemsToRetireve);

		/// <summary>
		/// Retrieve the top used tags for all approved items.
		/// </summary>
		/// <param name="numberOfItemsToRetireve">The number of items to retireve.</param>
		///<param name="includeFuturesPosts">if set to <c>true</c> the result will include the tags used in futures <see cref="Post"/>.</param>
		///<returns>
		///	Return a list of <see cref="TagItem"/>.
		///	The return item could be null if there isn't items into the repository.
		///</returns>
		///<exception cref="ArgumentOutOfRangeException"> If <paramref name="numberOfItemsToRetireve"/> is lesser than 1.</exception>
		IList<TagDto> GetTopTags(int numberOfItemsToRetireve, bool includeFuturesPosts);

		/// <summary>
		/// Retrieve the top used tags for all approved items.
		/// </summary>
		/// <param name="numberOfItemsToRetireve">The number of items to retireve.</param>
		///<param name="includeFuturesPosts">if set to <c>true</c> the result will include the tags used in futures <see cref="Post"/>.</param>
		///<param name = "enableTracking">if set to <c>true</c> the tracking system of the return object will be enable.</param>
		///<returns>
		///	Return a list of <see cref="TagItem"/>.
		///	The return item could be null if there isn't items into the repository.
		///</returns>
		///<exception cref="ArgumentOutOfRangeException"> If <paramref name="numberOfItemsToRetireve"/> is lesser than 1.</exception>
		IList<TagDto> GetTopTags(int numberOfItemsToRetireve, bool includeFuturesPosts, bool enableTracking);
	}
}
